How to Generate PDF from Franklin.jl Sites

date	2025-08-25

This document is generated by LLM

Overview

This guide explains how to convert Franklin.jl static sites into PDF documents using wkhtmltopdf. Franklin.jl is a popular static site generator for Julia that supports embedded code execution and mathematical notation.

Prerequisites

Julia with Franklin.jl package
wkhtmltopdf (brew install wkhtmltopdf or sudo apt-get install wkhtmltopdf)

Step-by-Step Process

1. Environment Setup

# Navigate to your Franklin.jl project directory
cd /path/to/your/franklin-site

# Verify wkhtmltopdf installation
which wkhtmltopdf

2. Install Project Dependencies

# Activate project environment and install dependencies
julia --project=. -e 'using Pkg; Pkg.instantiate()'

# Install any missing packages (common ones)
julia --project=. -e 'using Pkg; Pkg.add("Weave")' # If using .jmd files

3. Build Franklin.jl Site

# Build the static site
julia --project=. -e 'using Franklin; serve(single=true, cleanup=false)'

This generates HTML files in the __site/ directory.

4. Generate PDF

Basic PDF (Single Page)

wkhtmltopdf \
    --enable-local-file-access \
    --page-size A4 \
    --orientation Portrait \
    --margin-top 0.75in \
    --margin-right 0.75in \
    --margin-bottom 0.75in \
    --margin-left 0.75in \
    "__site/index.html" \
    "output.pdf"

Comprehensive PDF (Multiple Pages)

Create a script to combine multiple pages:

#!/bin/bash
# generate_pdf.sh

# Define pages to include
pages=(
    "__site/index.html"
    "__site/section1/index.html"
    "__site/section2/index.html"
    # Add more pages as needed
)

# Generate comprehensive PDF
wkhtmltopdf \
    --enable-local-file-access \
    --page-size A4 \
    --orientation Portrait \
    --margin-top 0.75in \
    --margin-right 0.75in \
    --margin-bottom 0.75in \
    --margin-left 0.75in \
    --print-media-type \
    --disable-smart-shrinking \
    "${pages[@]}" \
    "complete-site.pdf"

Common Issues and Solutions

Missing Dependencies

Problem: Package not found errors during build Solution:

julia --project=. -e 'using Pkg; Pkg.instantiate()'
julia --project=. -e 'using Pkg; Pkg.add("MissingPackage")'

CSS Loading Issues

Problem: Styles not applied in PDF Solution: Use --enable-local-file-access flag

Large Documents

Problem: Memory issues or timeouts Solution:

Increase timeout: --javascript-delay 5000
Process sections separately and combine later

Image Loading Failures

Problem: External images fail to load Solution:

Download images locally
Use --load-error-handling ignore for non-critical images

Key wkhtmltopdf Options

--enable-local-file-access - Load local CSS/assets
--page-size A4 --margin-* 0.75in - Page formatting
--print-media-type --disable-smart-shrinking - Better layout
--javascript-delay 2000 - Wait for JS rendering

Alternative Methods

Using Puppeteer (Node.js)

const puppeteer = require('puppeteer');
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('file:///path/to/__site/index.html');
await page.pdf({path: 'output.pdf', format: 'A4'});

Using Weasyprint (Python)

import weasyprint
weasyprint.HTML(filename='__site/index.html').write_pdf('output.pdf')